<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>CML/Golem dictionary syntax &mdash; Golem v1.0 documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
          URL_ROOT:    '',
          VERSION:     '1.0',
          COLLAPSE_MODINDEX: false,
          FILE_SUFFIX: ''
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/interface.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="contents" title="Global table of contents" href="contents.html" />
    <link rel="index" title="Global index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="top" title="Golem v1.0 documentation" href="index.html" />
    <link rel="next" title="Using the Golem library" href="usinglibrary.html" />
    <link rel="prev" title="Developing CML/Golem dictionaries" href="makingdictionaries.html" />
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="usinglibrary.html" title="Using the Golem library"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="makingdictionaries.html" title="Developing CML/Golem dictionaries"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Golem v1.0 documentation</a> &raquo;</li>
      </ul>
    </div>
    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  
  <div class="section" id="cml-golem-dictionary-syntax">
<h1 id="cml-golem-dictionary-syntax">CML/Golem dictionary syntax<a class="headerlink" href="#cml-golem-dictionary-syntax" title="Permalink to this headline">¶</a></h1>
<p>Here, we&#8217;ll go through one entry from a very small CML/Golem dictionary, which you can find in your Golem distribution in <tt class="docutils literal"><span class="pre">GOLEM/docs/AnnotatedDictionaryEntries.xml</span></tt>.</p>
<div class="highlight"><pre><span class="cp">&lt;?xml version=&quot;1.0&quot;?&gt;</span>
  <span class="c">&lt;!--  This example&#39;s derived from a dictionary for the CASTEP</span>
<span class="c">        code; you can find it at http://www.castep.org/ --&gt;</span>
<span class="nt">&lt;dictionary</span>
  <span class="na">namespace=</span><span class="s">&quot;http://www.castep.org/castep/dictionary&quot;</span>
  <span class="na">dictionaryPrefix=</span><span class="s">&quot;castep&quot;</span>
  <span class="na">title=</span><span class="s">&quot;CASTEP Dictionary&quot;</span>
  <span class="na">xmlns=</span><span class="s">&quot;http://www.xml-cml.org/schema&quot;</span>
  <span class="na">xmlns:castep=</span><span class="s">&quot;http://www.castep.org/cml/dictionary/&quot;</span>
  <span class="na">xmlns:h=</span><span class="s">&quot;http://www.w3.org/1999/xhtml/&quot;</span>
  <span class="na">xmlns:cml=</span><span class="s">&quot;http://www.xml-cml.org/schema&quot;</span>
  <span class="na">xmlns:xsd=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema&quot;</span>
  <span class="na">xmlns:golem=</span><span class="s">&quot;http://www.lexical.org.uk/golem&quot;</span>
  <span class="na">xmlns:xsl=</span><span class="s">&quot;http://www.w3.org/1999/XSL/Transform&quot;</span><span class="nt">&gt;</span>
</pre></div>
<p>You specify the three attributes above here - a URL for the dictionary
(which you can think of as a machine-readable name; pick something
unique at a domain you control), the dictionaryPrefix (short name for
the dictionary), and the dictionary title (which is the title people using the
dictionary&#8217;ll see.)</p>
<p>As mentioned earlier, the dictionary generator will add the namespaces for
you, but if you&#8217;re writing your own dictionary for whatever reason, just copy
them across as they are here.</p>
<div class="highlight"><pre><span class="nt">&lt;entry</span> <span class="na">id=</span><span class="s">&quot;xcFunctional&quot;</span> <span class="na">term=</span><span class="s">&quot;Exchange-Correlation Functional&quot;</span><span class="nt">&gt;</span>
</pre></div>
<p>The <tt class="docutils literal"><span class="pre">id</span></tt> must be unique within the dictionary. The term is designed for
documentation, so should be as pithy as you can make it.</p>
<div class="section" id="definition-and-description">
<h2 id="definition-and-description"><tt class="docutils literal"><span class="pre">&lt;definition&gt;</span></tt> and <tt class="docutils literal"><span class="pre">&lt;description&gt;</span></tt><a class="headerlink" href="#definition-and-description" title="Permalink to this headline">¶</a></h2>
<p>Next, we deal with documenting what this dictionary entry means.</p>
<div class="highlight"><pre><span class="nt">&lt;definition&gt;</span>
  The exchange-correlation functional used.
<span class="nt">&lt;/definition&gt;</span>
</pre></div>
<p>The <tt class="docutils literal"><span class="pre">definition</span></tt> is a one-sentence description of the concept this
dictionary entry defines.</p>
<p>Next, <tt class="docutils literal"><span class="pre">&lt;description&gt;</span></tt> - note that <tt class="docutils literal"><span class="pre">h:</span></tt> here was defined, above, to be
bound to the XHTML namespace:</p>
<div class="highlight"><pre><span class="nt">&lt;description&gt;</span>
    <span class="nt">&lt;h:div</span> <span class="na">class=</span><span class="s">&quot;dictDescription&quot;</span><span class="nt">&gt;</span>
      The exchange-correlation functional used in a given simulation.
      Available values for this are:
      <span class="nt">&lt;h:ul&gt;</span>
        <span class="nt">&lt;h:li&gt;</span>
          <span class="nt">&lt;h:strong&gt;</span>LDA<span class="nt">&lt;/h:strong&gt;</span>, the Local Density Approximation
        <span class="nt">&lt;/h:li&gt;</span>
        <span class="nt">&lt;h:li&gt;</span>
          <span class="nt">&lt;h:strong&gt;</span>PW91<span class="nt">&lt;/h:strong&gt;</span>, Perdew and Wang&#39;s 1991 formulation
        <span class="nt">&lt;/h:li&gt;</span>
        <span class="nt">&lt;h:li&gt;</span>
          <span class="nt">&lt;h:strong&gt;</span>PBE<span class="nt">&lt;/h:strong&gt;</span>,
          Perdew, Burke and Enzerhof&#39;s original GGA functional
        <span class="nt">&lt;/h:li&gt;</span>
        <span class="nt">&lt;h:li&gt;</span>
          <span class="nt">&lt;h:strong&gt;</span>RPBE<span class="nt">&lt;/h:strong&gt;</span>, Hammer et al&#39;s revised PBE functional
        <span class="nt">&lt;/h:li&gt;</span>
      <span class="nt">&lt;/h:ul&gt;</span>
    <span class="nt">&lt;/h:div&gt;</span>
<span class="nt">&lt;/description&gt;</span>
</pre></div>
<p><tt class="docutils literal"><span class="pre">&lt;description&gt;</span></tt> contains a longer description - ideally, documentation
for the term. As mentioned above, this takes the form of XHTML.</p>
<div class="highlight"><pre><span class="nt">&lt;metadataList&gt;</span>
  <span class="nt">&lt;metadata</span> <span class="na">name=</span><span class="s">&quot;dc:contributor&quot;</span> <span class="na">content=</span><span class="s">&quot;golem-kiln&quot;</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/metadataList&gt;</span>
</pre></div>
<p>Optionally, <tt class="docutils literal"><span class="pre">&lt;metadataList&gt;</span></tt> - which contains CML <tt class="docutils literal"><span class="pre">&lt;metadata&gt;</span></tt> - can
be used to document the provenance of a dictionary entry (for instance,
who wrote it).</p>
</div>
<div class="section" id="golem-xpath">
<h2 id="golem-xpath"><tt class="docutils literal"><span class="pre">&lt;golem:xpath&gt;</span></tt><a class="headerlink" href="#golem-xpath" title="Permalink to this headline">¶</a></h2>
<p>Next, we need to tell our programs how to find the data this entry is
describing; we do that by giving an XPath expression pointing to where it can
be found.:</p>
<div class="highlight"><pre><span class="c">&lt;!-- Where this concept can be found in CML documents which</span>
<span class="c">use this dialect - usually inferred by the dictionary builder  --&gt;</span>
<span class="nt">&lt;golem:xpath&gt;</span>./cml:parameter[@dictRef=&quot;castep:xcFunctional&quot;]<span class="nt">&lt;/golem:xpath&gt;</span>
</pre></div>
</div>
<div class="section" id="golem-template">
<h2 id="golem-template"><tt class="docutils literal"><span class="pre">&lt;golem:template&gt;</span></tt><a class="headerlink" href="#golem-template" title="Permalink to this headline">¶</a></h2>
<p>Once we have found the data, we need to know to read it. Here, the data that
we&#8217;re trying to read looks something like</p>
<div class="highlight"><pre><span class="nt">&lt;parameter</span> <span class="na">dictRef=</span><span class="s">&quot;castep:xcFunctional&quot;</span> <span class="na">name=</span><span class="s">&quot;Exchange-Correlation Functional&quot;</span><span class="nt">&gt;</span>
  <span class="nt">&lt;scalar</span> <span class="na">dataType=</span><span class="s">&quot;xsd:string&quot;</span><span class="nt">&gt;</span>PBE<span class="nt">&lt;/scalar&gt;</span>
<span class="nt">&lt;/parameter&gt;</span>
</pre></div>
<p>Here, we&#8217;re trying to read a scalar (a number or string). Golem templates use
XSLT to convert pieces of CML, like this one, into JSON objects of the form
<tt class="docutils literal"><span class="pre">[value,</span> <span class="pre">&quot;u:units&quot;]</span></tt>, where <tt class="docutils literal"><span class="pre">u</span></tt> is the namespace in which the units are
declared.</p>
<p>The golem dictionary generation tools &#8220;know about&#8221; - i.e., have templates
for the following tags, assuming they are used in the same way as FoX uses
them:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">&lt;scalar&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">&lt;array&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">&lt;matrix&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">&lt;cellParameter&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">&lt;metadata&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">&lt;lattice&gt;</span></tt></li>
<li><tt class="docutils literal"><span class="pre">&lt;atomArray&gt;</span></tt></li>
</ul>
<p>So if the data you are reading is in one of these tags, then the following
will let you read it:</p>
<div class="highlight"><pre><span class="nt">&lt;golem:template</span> <span class="na">call=</span><span class="s">&quot;scalar&quot;</span> <span class="na">role=</span><span class="s">&quot;getvalue&quot;</span> <span class="na">binding=</span><span class="s">&quot;pygolem_serialization&quot;</span> <span class="nt">/&gt;</span>
</pre></div>
<p>Here, the value of <tt class="docutils literal"><span class="pre">call</span></tt> will, typically, correspond to the name of
the tag which has the actual data in: so here it&#8217;s &#8220;scalar&#8221;.</p>
<p>If additional information (say, extra properties on each <tt class="docutils literal"><span class="pre">atom</span></tt> in an
<tt class="docutils literal"><span class="pre">atomArray</span></tt>) is added, the read will still succeed, but the extra
information <em>will</em> be ignored; either you will need to modify the template for
that type, or arrange to read out that extra information in another way (such
as using <tt class="docutils literal"><span class="pre">etree</span></tt> methods, as in the examples later in this documentation).</p>
<p>If your data is contained in some other tag, and you wish to read it directly
using Golem, then you need to:</p>
<ul>
<li><p class="first">Write a dictionary entry with the tagname as the id (i.e. <tt class="docutils literal"><span class="pre">&lt;entry</span> <span class="pre">id=&quot;newEntry&quot;</span> <span class="pre">...&gt;</span></tt>);</p>
</li>
<li><p class="first">Write an XSLT stylesheet which produces a JSON document of the form <tt class="docutils literal"><span class="pre">[</span> <span class="pre">newEntry_value,</span> <span class="pre">&quot;units:newEntry_units&quot;</span> <span class="pre">]</span></tt> when run over the data. For example, lattice vectors are represented by markup of the form:</p>
<div class="highlight"><pre><span class="nt">&lt;lattice&gt;</span>
    <span class="nt">&lt;latticeVector&gt;</span>a b c<span class="nt">&lt;/latticeVector&gt;</span>
    <span class="nt">&lt;latticeVector&gt;</span>d e f<span class="nt">&lt;/latticeVector&gt;</span>
    <span class="nt">&lt;latticeVector&gt;</span>g h i<span class="nt">&lt;/latticeVector&gt;</span>
<span class="nt">&lt;/lattice&gt;</span>
</pre></div>
</li>
<li><p class="first">which we associate with a stylesheet</p>
<div class="highlight"><pre>  <span class="k">&lt;xsl:stylesheet</span> <span class="na">xmlns:xsl=</span><span class="s">&quot;http://www.w3.org/1999/XSL/Transform&quot;</span> <span class="na">xmlns:cml</span>
<span class="na">=</span><span class="s">&quot;http://www.xml-cml.org/schema&quot;</span> <span class="na">xmlns:str=</span><span class="s">&quot;http://exslt.org/strings&quot;</span> <span class="na">version=</span><span class="s">&quot;1</span>
<span class="s">.0&quot;</span> <span class="na">extension-element-prefixes=</span><span class="s">&quot;str&quot;</span><span class="nt">&gt;</span>
    <span class="k">&lt;xsl:output</span> <span class="na">method=</span><span class="s">&quot;text&quot;</span><span class="nt">/&gt;</span>

    <span class="k">&lt;xsl:template</span> <span class="na">match=</span><span class="s">&quot;/&quot;</span><span class="nt">&gt;</span>
      <span class="k">&lt;xsl:apply-templates</span><span class="nt">/&gt;</span>
    <span class="k">&lt;/xsl:template&gt;</span>

    <span class="k">&lt;xsl:template</span> <span class="na">match=</span><span class="s">&quot;cml:lattice&quot;</span><span class="nt">&gt;</span>
      <span class="k">&lt;xsl:text</span><span class="nt">&gt;</span>[[<span class="k">&lt;/xsl:text&gt;</span>
      <span class="k">&lt;xsl:for-each</span> <span class="na">select=</span><span class="s">&quot;cml:latticeVector&quot;</span><span class="nt">&gt;</span>
        <span class="k">&lt;xsl:text</span><span class="nt">&gt;</span>[<span class="k">&lt;/xsl:text&gt;</span>
        <span class="k">&lt;xsl:for-each</span> <span class="na">select=</span><span class="s">&quot;str:tokenize(string(.), &#39; &#39;)&quot;</span><span class="nt">&gt;</span>
          <span class="k">&lt;xsl:choose</span><span class="nt">&gt;</span>
            <span class="k">&lt;xsl:when</span> <span class="na">test=</span><span class="s">&quot;position() != last()&quot;</span><span class="nt">&gt;</span>
              <span class="k">&lt;xsl:value-of</span> <span class="na">select=</span><span class="s">&quot;.&quot;</span><span class="nt">/&gt;</span><span class="k">&lt;xsl:text</span><span class="nt">&gt;</span>,<span class="k">&lt;/xsl:text&gt;</span>
            <span class="k">&lt;/xsl:when&gt;</span>
            <span class="k">&lt;xsl:otherwise</span><span class="nt">&gt;</span>
              <span class="k">&lt;xsl:value-of</span> <span class="na">select=</span><span class="s">&quot;.&quot;</span><span class="nt">/&gt;</span>
            <span class="k">&lt;/xsl:otherwise&gt;</span>
          <span class="k">&lt;/xsl:choose&gt;</span>
        <span class="k">&lt;/xsl:for-each&gt;</span>
        <span class="k">&lt;xsl:choose</span><span class="nt">&gt;</span>
          <span class="k">&lt;xsl:when</span> <span class="na">test=</span><span class="s">&quot;position() != last()&quot;</span><span class="nt">&gt;</span>
            <span class="k">&lt;xsl:text</span><span class="nt">&gt;</span>],<span class="k">&lt;/xsl:text&gt;</span>
          <span class="k">&lt;/xsl:when&gt;</span>
          <span class="k">&lt;xsl:otherwise</span><span class="nt">&gt;</span>
            <span class="k">&lt;xsl:text</span><span class="nt">&gt;</span>]<span class="k">&lt;/xsl:text&gt;</span>
          <span class="k">&lt;/xsl:otherwise&gt;</span>
        <span class="k">&lt;/xsl:choose&gt;</span>
      <span class="k">&lt;/xsl:for-each&gt;</span>
      <span class="k">&lt;xsl:text</span><span class="nt">&gt;</span>], &quot;A**-1&quot;]<span class="k">&lt;/xsl:text&gt;</span>
    <span class="k">&lt;/xsl:template&gt;</span>
  <span class="k">&lt;/xsl:stylesheet&gt;</span>
</pre></div>
</li>
<li><p class="first">Put this in your dictionary entry. Here&#8217;s how you do that:</p>
<div class="highlight"><pre><span class="nt">&lt;golem:template</span> <span class="na">role=</span><span class="s">&quot;getvalue&quot;</span> <span class="na">binding=</span><span class="s">&quot;pygolem_serialization&quot;</span><span class="nt">&gt;</span>
  <span class="k">&lt;xsl:stylesheet</span><span class="nt">&gt;</span>
    <span class="c">&lt;!-- stylesheet goes here --&gt;</span>
  <span class="k">&lt;/xsl:stylesheet&gt;</span>
<span class="nt">&lt;/golem:template&gt;</span>
</pre></div>
</li>
<li><p class="first">Add <tt class="docutils literal"><span class="pre">&lt;golem:template</span> <span class="pre">call=&quot;newEntry&quot;</span> <span class="pre">role=&quot;getvalue&quot;</span> <span class="pre">binding=&quot;pygolem_serialization&quot;</span> <span class="pre">/&gt;</span></tt> to the dictionary entries which&#8217;ll use this new template to read their data.</p>
</li>
</ul>
<p>The <tt class="docutils literal"><span class="pre">role</span></tt> of templates determines how they are used: all templates used for
reading data with Golem should have <tt class="docutils literal"><span class="pre">role=&quot;getvalue&quot;</span></tt> and
<tt class="docutils literal"><span class="pre">binding=&quot;pygolem_serialization&quot;</span></tt>. This is the only special case in
<tt class="docutils literal"><span class="pre">role</span></tt>; but you can add other templates with different roles, too. These get
mapped onto functions if you&#8217;re using the Golem library: for instance, if
you&#8217;ve got a dictionary <tt class="docutils literal"><span class="pre">d</span></tt> with namespace <tt class="docutils literal"><span class="pre">n</span></tt>, then (in a Python
interactive shell):</p>
<div class="highlight"><pre>&gt;&gt;&gt; xcFunctional_entry = d[&quot;{%s}xcFunctional&quot; % n]
&gt;&gt;&gt; print str(xcFunctional_entry.arb_to_input(&quot;RPBE&quot;))
</pre></div>
<p>will print out the value of this template when passed &#8220;RPBE&#8221; as
an argument.</p>
<div class="highlight"><pre><span class="c">&lt;!--</span>
<span class="c">Arguments are labelled p1, p2... pn in the template; if you&#39;re writing</span>
<span class="c">a template to which you&#39;re going to pass arguments, you need to set</span>
<span class="c">the @binding attribute to &quot;input&quot;, as here, and @input to &quot;external&quot;</span>
<span class="c">(meaning it takes externally-provided arguments, not XML).</span>
<span class="c">--&gt;</span>

<span class="nt">&lt;golem:template</span> <span class="na">role=</span><span class="s">&quot;arb_to_input&quot;</span> <span class="na">binding=</span><span class="s">&quot;input&quot;</span> <span class="na">input=</span><span class="s">&quot;external&quot;</span><span class="nt">&gt;</span>
  <span class="k">&lt;xsl:stylesheet</span> <span class="na">version=</span><span class="s">&#39;1.0&#39;</span>
                  <span class="na">xmlns:xsl=</span><span class="s">&#39;http://www.w3.org/1999/XSL/Transform&#39;</span>
                  <span class="na">xmlns:cml=</span><span class="s">&#39;http://www.xml-cml.org/schema&#39;</span><span class="nt">&gt;</span>
    <span class="k">&lt;xsl:strip-space</span> <span class="na">elements=</span><span class="s">&quot;*&quot;</span> <span class="nt">/&gt;</span>
    <span class="k">&lt;xsl:output</span> <span class="na">method=</span><span class="s">&quot;text&quot;</span> <span class="nt">/&gt;</span>
    <span class="k">&lt;xsl:param</span> <span class="na">name=</span><span class="s">&quot;p1&quot;</span> <span class="nt">/&gt;</span>
    <span class="k">&lt;xsl:template</span> <span class="na">match=</span><span class="s">&quot;/&quot;</span><span class="nt">&gt;</span>
      <span class="k">&lt;xsl:text</span><span class="nt">&gt;</span>XC_FUNCTIONAL <span class="k">&lt;/xsl:text&gt;&lt;xsl:value-of</span> <span class="na">select=</span><span class="s">&quot;$p1&quot;</span> <span class="nt">/&gt;</span>
    <span class="k">&lt;/xsl:template&gt;</span>
  <span class="k">&lt;/xsl:stylesheet&gt;</span>
<span class="nt">&lt;/golem:template&gt;</span>
</pre></div>
</div>
<div class="section" id="golem-synonym-et-al">
<h2 id="golem-synonym-et-al"><tt class="docutils literal"><span class="pre">&lt;golem:synonym&gt;</span></tt> et al<a class="headerlink" href="#golem-synonym-et-al" title="Permalink to this headline">¶</a></h2>
<p>In this section, we describe the terms which can be used to draw relations
between concepts in dictionaries. Those relationships can then be used by
the Golem library to enable equivalent concepts to be looked up at once,
rather than having to check them all separately.</p>
<p>First, <tt class="docutils literal"><span class="pre">&lt;golem:implements&gt;</span></tt>; if entry A <tt class="docutils literal"><span class="pre">implements</span></tt> entry B, then if a
piece of CML satisfies the definition of term B, it also satisfies the
definition of term A. In other words, term A is an <em>implementation</em> (analogous
to a subclass) of term B.</p>
<div class="highlight"><pre><span class="nt">&lt;golem:implements&gt;</span>convertibleToInput<span class="nt">&lt;/golem:implements&gt;</span>
<span class="nt">&lt;golem:implements&gt;</span>value<span class="nt">&lt;/golem:implements&gt;</span>
<span class="nt">&lt;golem:implements</span> <span class="na">namespace=</span><span class="s">&quot;http://www.example.com/example/&quot;</span><span class="nt">&gt;</span>absolute<span class="nt">&lt;/golem:implements&gt;</span>
</pre></div>
<p>In the final case here, the term <tt class="docutils literal"><span class="pre">absolute</span></tt> resides in a different
dictionary with the given namespace; to be able to make use of this in
your code, your program will need to load both dictionaries.</p>
<p>If two concepts are synonymous, then any instance of one concept is equivalent
to an instance of the other, although they may be serialized differently.
To implement that in a dictionary, add the following to <tt class="docutils literal"><span class="pre">concept1</span></tt>&#8216;s dictionary entry:</p>
<div class="highlight"><pre><span class="nt">&lt;golem:synonym&gt;</span>concept2<span class="nt">&lt;/golem:synonym&gt;</span>
</pre></div>
<p>Or if concept2 resides in a different dictionary with a different namespace:</p>
<blockquote>
&lt;golem:synonym namespace=&#8221;http://namespace2/&#8221;&gt;concept2&lt;/golem:synonym&gt;</blockquote>
<p>although, as above, you will not be able to make use of this
relationship without explicitly loading the second dictionary.
Synonyms are <em>symmetric</em>, unlike <tt class="docutils literal"><span class="pre">implements</span></tt>; stating that <tt class="docutils literal"><span class="pre">a</span></tt>
implements <tt class="docutils literal"><span class="pre">b</span></tt> does not imply that <tt class="docutils literal"><span class="pre">b</span></tt> implements <tt class="docutils literal"><span class="pre">a</span></tt>, whereas
stating that <tt class="docutils literal"><span class="pre">a</span></tt> is synonymous with <tt class="docutils literal"><span class="pre">b</span></tt> <em>does</em> imply that <tt class="docutils literal"><span class="pre">b</span></tt> is
synonymous with <tt class="docutils literal"><span class="pre">a</span></tt>. It is sufficient to specify the synonym on either
one of these concepts; it doesn&#8217;t need to be given on both.</p>
<p>In both cases, when searching for a concept using the <tt class="docutils literal"><span class="pre">findin</span></tt> method (in
the following section on how to use the Golem libraries), all synonyms and
implementations of the current concept are found.</p>
<p><tt class="docutils literal"><span class="pre">&lt;golem:seeAlso&gt;</span></tt> is used to denote any other relationship between concepts;
it does not imply any particular relationship, but alerts the user that it may
be worth looking at the other entry. This is mostly of use in
dictionary-browsing applications and similar tools, where it can be used (for
instance) to implement a thesaurus.</p>
<p>We may also want to represent certain aspects of document structure in the
dictionary. This is particularly useful when you are wanting to evaluate
&#8220;everything in a section of the document&#8221;; for example, &#8220;every input
parameter&#8221;. We can denote these relationships using <tt class="docutils literal"><span class="pre">&lt;golem:childOf&gt;</span></tt>.</p>
<p>A <tt class="docutils literal"><span class="pre">&lt;golem:childOf&gt;</span></tt> is found as a childNode (in the XML sense) of the
CML representation of another node in the dictionary:</p>
<div class="highlight"><pre><span class="nt">&lt;golem:childOf&gt;</span>input<span class="nt">&lt;/golem:childOf&gt;</span>
</pre></div>
<p>So, here, <tt class="docutils literal"><span class="pre">xcFunctional</span></tt> is found in the child nodes of the CML
representation of the dictionary term <tt class="docutils literal"><span class="pre">input</span></tt>.</p>
</div>
<div class="section" id="golem-possiblevalues">
<h2 id="golem-possiblevalues"><tt class="docutils literal"><span class="pre">&lt;golem:possibleValues&gt;</span></tt><a class="headerlink" href="#golem-possiblevalues" title="Permalink to this headline">¶</a></h2>
<p>The range, and type, of data one expects for a given concept can be
given with <tt class="docutils literal"><span class="pre">&lt;golem:possibleValues&gt;</span></tt>.</p>
<div class="highlight"><pre><span class="nt">&lt;golem:possibleValues</span> <span class="na">type=</span><span class="s">&quot;string&quot;</span><span class="nt">&gt;</span>
  <span class="nt">&lt;golem:enumeration&gt;</span> <span class="c">&lt;!--  contains the possible values for this concept --&gt;</span>
    <span class="nt">&lt;golem:value&gt;</span>LDA<span class="nt">&lt;/golem:value&gt;</span> <span class="c">&lt;!--  and one of these for each value --&gt;</span>
    <span class="nt">&lt;golem:value&gt;</span>PW91<span class="nt">&lt;/golem:value&gt;</span>
    <span class="nt">&lt;golem:value&gt;</span>PBE<span class="nt">&lt;/golem:value&gt;</span>
    <span class="nt">&lt;golem:value&gt;</span>RPBE<span class="nt">&lt;/golem:value&gt;</span>
  <span class="nt">&lt;/golem:enumeration&gt;</span>
<span class="nt">&lt;/golem:possibleValues&gt;</span>
</pre></div>
<p>The <tt class="docutils literal"><span class="pre">type</span></tt> of data may be <tt class="docutils literal"><span class="pre">int</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>, <tt class="docutils literal"><span class="pre">string</span></tt>, or <tt class="docutils literal"><span class="pre">matrix</span></tt>.
<tt class="docutils literal"><span class="pre">int``s</span> <span class="pre">(and</span> <span class="pre">analogously</span> <span class="pre">``floats</span></tt>) are specified as follows:</p>
<div class="highlight"><pre><span class="nt">&lt;golem:possibleValues</span> <span class="na">type=</span><span class="s">&quot;int&quot;</span><span class="nt">&gt;</span>
  <span class="nt">&lt;golem:range&gt;</span>
    <span class="nt">&lt;golem:minimum&gt;</span>2<span class="nt">&lt;/golem:minimum&gt;</span>
  <span class="nt">&lt;/golem:range&gt;</span>
<span class="nt">&lt;/golem:possibleValues&gt;</span>
</pre></div>
<p>Matrices are a little more complex: you can specify both the dimension of the
matrix and the type of the data therein. For example:</p>
<div class="highlight"><pre><span class="nt">&lt;golem:possibleValues</span> <span class="na">type=</span><span class="s">&quot;matrix&quot;</span><span class="nt">&gt;</span>
    <span class="c">&lt;!--  The data type of the matrix *elements* goes in here -</span>
<span class="c">    so this is a matrix of floats... --&gt;</span>
  <span class="nt">&lt;golem:matrix</span> <span class="na">dimensionx=</span><span class="s">&quot;3&quot;</span> <span class="na">dimensiony=</span><span class="s">&quot;3&quot;</span> <span class="na">type=</span><span class="s">&quot;float&quot;</span> <span class="na">symmetric=</span><span class="s">&quot;false&quot;</span><span class="nt">/&gt;</span>
  <span class="c">&lt;!--  The @symmetric element on golem:matrix specifies whether the</span>
<span class="c">  matrix is symmetric. If it is, only the upper diagonal elements</span>
<span class="c">  should be given; if not, the full matrix is expected. --&gt;</span>

  <span class="c">&lt;!-- If you give a &lt;golem:range&gt; here, it applies to all the</span>
<span class="c">        elements in the matrix: --&gt;</span>
   <span class="nt">&lt;golem:range&gt;</span>
     <span class="nt">&lt;golem:minimum&gt;</span>0<span class="nt">&lt;/golem:minimum&gt;</span>
     <span class="nt">&lt;golem:maximum&gt;</span>10<span class="nt">&lt;/golem:maximum&gt;</span>
   <span class="nt">&lt;/golem:range&gt;</span>

   <span class="c">&lt;!-- constrains the matrix elements to lie in the range</span>
<span class="c">        0 &lt;= element &lt;= 10. --&gt;</span>
<span class="nt">&lt;/golem:possibleValues&gt;</span>
</pre></div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3>Table Of Contents</h3>
            <ul>
<li><a class="reference external" href="">CML/Golem dictionary syntax</a><ul>
<li><a class="reference external" href="#definition-and-description"><tt class="docutils literal"><span class="pre">&lt;definition&gt;</span></tt> and <tt class="docutils literal"><span class="pre">&lt;description&gt;</span></tt></a></li>
<li><a class="reference external" href="#golem-xpath"><tt class="docutils literal"><span class="pre">&lt;golem:xpath&gt;</span></tt></a></li>
<li><a class="reference external" href="#golem-template"><tt class="docutils literal"><span class="pre">&lt;golem:template&gt;</span></tt></a></li>
<li><a class="reference external" href="#golem-synonym-et-al"><tt class="docutils literal"><span class="pre">&lt;golem:synonym&gt;</span></tt> et al</a></li>
<li><a class="reference external" href="#golem-possiblevalues"><tt class="docutils literal"><span class="pre">&lt;golem:possibleValues&gt;</span></tt></a></li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="makingdictionaries.html" title="previous chapter">Developing CML/Golem dictionaries</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="usinglibrary.html" title="next chapter">Using the Golem library</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="_sources/dictionarysyntax.txt">Show Source</a></li>
            </ul>
            <h3>Quick search</h3>
            <form class="search" action="search.html" method="get">
              <input type="text" name="q" size="18" /> <input type="submit" value="Go" />
              <input type="hidden" name="check_keywords" value="yes" />
              <input type="hidden" name="area" value="default" />
            </form>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="usinglibrary.html" title="Using the Golem library"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="makingdictionaries.html" title="Developing CML/Golem dictionaries"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Golem v1.0 documentation</a> &raquo;</li>
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright 2008, Andrew Walkingshaw.
      Last updated on Oct 01, 2008.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
    </div>
  </body>
</html>